nice_things/lang/PipeStatus.sh

The PipeStatus class allows to detect when errors occur at any stage of a pipeline. It's meant to provide functionality similar to setting the pipefail shell option in bash, but compatible with any POSIX shell.

Since commands in a pipeline run in a subshell, this class uses a runtime file as a side-channel to record the status code returned by the commands. The resulting status of the class is the status code of the first command to fail, or 0 if all commands succeed.

An object of this class can be used only once. The catch method is a destructor, after it has been invoked, the object cannot be used anymore.

Usage examples

#{{{
import "{ PipeStatus }" from nice_things/lang/PipeStatus.sh
import "{ catch }" from nice_things/lang/PipeStatus_catch.sh
import "{ try }" from nice_things/lang/PipeStatus_try.sh
#}}}
ps=#{{{ new PipeStatus }}}
try "$ps" command : | try "$ps" command :
catch "$ps" || {
	log_error "Pipeline failed with status $?"
}

PipeStatus

Since 0.3.0 · Source

import "{ PipeStatus }" from nice_things/lang/PipeStatus.sh

Synopsis
PipeStatus <&self>

Configuration
–

Description
Constructor for the PipeStatus class.

Usually, this constructor function should be invoked with the new macro, which takes care of creating the <&self> reference to the newly created object.

Options
–

Operands
–

Stdin
–

Stdout
–

Stderr
–

Exit status

• 0: Successful completion.
• 12: Invalid self reference <&self> (abort).
• 123: Unexpected error (abort).

Abort

• Aborts if self reference <&self> is invalid.
• Aborts on unexpected error.

Usage examples

ps=#{{{ new PipeStatus }}}

catch

Since 0.3.0 · Source

import "{ catch }" from nice_things/lang/PipeStatus_catch.sh

Synopsis
catch <&self>

Configuration
–

Description
Check if any command has failed. Returns the status code of the first command to fail, or 0 if all commands succeeded.

Options
–

Operands
<&self>: Self reference.

Stdin
–

Stdout
–

Stderr
–

Exit status

• 0: Successful completion.
• >0: Some command failed.
• 12: Invalid self reference <&self> (abort).
• 122: Some command failed (if fails to retrieve correct status code).

Abort
Aborts if self reference <&self> is invalid.

Usage examples

catch "$ps" || log_error "Pipeline failed with status $?"

try

Since 0.3.0 · Source

import "{ try }" from nice_things/lang/PipeStatus_try.sh

Synopsis
try <&self> <command> [<arg>…]

Configuration
–

Description
Execute <command> and save its returned status code.

Options
–

Operands

• <&self>: Self reference.
• <command>: The command to execute.
• <arg>: Optional argument to <command>.

Stdin
–

Stdout
–

Stderr
–

Exit status
0: Successful completion.

Abort
Always exits the current process.

Usage examples

try "$ps" command : | try "$ps" command :